home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / doors_1 / kmail270.zip / KMAIL.DOC < prev    next >
Text File  |  1991-02-24  |  22KB  |  516 lines
  1.                        Kmail Version  2.68
  2.                          Copyright 1990
  3.                                by
  4.                            Ken Krueger
  5.  
  6.                          Twin  Peaks  BBS
  7.             (303)-651-0225 - Hayes Ultra v.32 v.42bis
  8.  
  9. Specifications:
  10. ---------------
  11.  
  12.   Produces QWK compatable mail packets.
  13.   Reads CNAMES.@@@ to obtain conference information.
  14.   Reads TPA to obtain User information.
  15.   Updates USER file via USERS.SYS interface.
  16.   Resets "Mail Waiting" flags after a successful packet download.
  17.   Fully network compatable. Opens all files in share mode.
  18.   Locks message base during updating.
  19.   Supports 1024 conferences.
  20.   Message packets compatable with RNET.
  21.   Extended conference packets require RNET v1.07 or later.
  22.   Message packets tested with EZ-RDR v1.33 and SLMR v1.05.
  23.  
  24.  
  25. Evaluation
  26. ----------
  27.  
  28.   This evaluation  version of  Kmail is  provided so  that you  and your
  29. users may may decide  if this program meets  your needs.  Kmail  is 100%
  30. fully functional for the "sysop" in local mode.  The callers are limited
  31. to 10 messages per conference and to 50 total messages per packet.
  32.  
  33. In addition, you may call Twin Peaks and obtain a one time 30-day full
  34. function demo-key to help complete your evaluation. No fuss no muss,
  35. first time callers can obtain the demo-key.
  36.  
  37.  
  38. 30 Day Demo Key
  39. ---------------
  40.  
  41.   To obtain the 30 day demo key, just call Twin Peaks. Join conf #19
  42. open door 9 and follow the instructions.
  43.  
  44.   In order for the Demo-Key to work, the name you use to register on
  45. Twin Peaks MUST exactly match the name in record #1 of your USERS file.
  46.  
  47.  
  48. Requirements
  49. ------------
  50.  
  51.    Dos 3.1 or greater.
  52.    PCBoard 14.5
  53.    DSZ     version 05/25/89 or later.
  54.    PKZIP   v1.10 or higher.
  55.    PK361   If you wish to support the ARC format.  (optional)
  56.    PUMA    If you wish to make it available.       (optional)
  57.  
  58. Installation
  59. ------------
  60.  
  61.    1. Create a KMAIL sub-directory to hold the Kmail distribution files.
  62.       Place all files in the archive into this directory.
  63.  
  64.    2. Create a work sub-directory such as C:\KWORK for Kmail to use.
  65.       ***CAUTION***  ***CAUTION***     All files are erased in this
  66.       directory during the mail packet creation process. DO NOT use an
  67.       existing directory that has good stuff in it! More detail below.
  68.  
  69.    3. Customize the KMAIL.CFG file. Ample comments are in the sample.
  70.       This is where you really customize the overall operation.
  71.       Parms 1-4 are passed along to the mail readers for their use.
  72.       While not critical, you should keep to the general outline in
  73.       the sample and customize them for your system.
  74.  
  75.  ==>  PARM 5: This one is important! This parm specifies the name of
  76.       the QWK mail packet that Kmail will create. While the name can be
  77.       anything, it would be best to have a name that is associated
  78.       with your BBS system name. (Do not specify a .extension here).
  79.  
  80.       The rest of the parms are optional. Among them are options to
  81.       control the number of messages based on connect speed, and
  82.       protocol transfer options. The default values are in the sample.
  83.  
  84.       DSZ is used as the main protocol and is activated via a call
  85.       to a BAT file which you may define in the KMAIL.CFG file. This
  86.       allows you to totally customize the DSZ parms to suit your
  87.       system. I just let it default to the standard PCBxx.BAT files
  88.       that I have setup for PCBoard. Be sure to include the BAT files
  89.       location in your DOS path! Kmail passes parms %1-%5 to the
  90.       BAT files just the same as PCBoard.
  91.  
  92.  
  93.       When a caller requests ╔════════════════════════════════════════╗
  94.       an external protocol,  ║       External Protocol Parameters     ║
  95.       PCBoard passes several ╠═════════╦══════════════════════════════╣
  96.       parameters to the      ║Parameter║         Description          ║
  97.       protocol batch file.   ╠═════════╬══════════════════════════════╣
  98.       These parameters are   ║   %1    ║COM Port Number.              ║
  99.       listed to the right.   ╟─────────╫──────────────────────────────╢
  100.                              ║   %2    ║PC to Modem Speed (DTE rate)  ║
  101.                              ╟─────────╫──────────────────────────────╢
  102.                              ║   %3    ║Filename to transfer.         ║
  103.                              ╟─────────╫──────────────────────────────╢
  104.                           ** ║   %4    ║Connect Speed shown by PCBoard║
  105.                              ╟─────────╫──────────────────────────────╢
  106.                              ║   %5    ║Carrier Speed.                ║
  107.                              ╚═════════╩══════════════════════════════╝
  108.  
  109.      ** The %4 field is not easily determined within Kmail, therefore
  110.         upon exit to the protocol BAT files, Kmail adjusts the %4
  111.         field to the same value as %5.
  112.  
  113.  
  114.       I have found the following works well with my Hayes 9600 v.42.
  115.  
  116.         PCBSZ.BAT
  117.               dsz ha bo est 0 %5 pB4096 sz -m %3
  118.  
  119.         PCBRZ.BAT
  120.               dsz ha slow est 0 %5 pB4096 z pr1 rz -m -p %3
  121.  
  122.  
  123.    4. Customize the KMAIL.CNF if necessary. This is a 2 or 3 line file.
  124.       The 1st line defines the interface routine that Kmail should
  125.       use, and the 2nd line defines the location of a work directory.
  126.  
  127.       If you are running a multi-node system, you will need a unique
  128.       CNF file for each node. (KMAIL1.CNF, KMAIL2.CNF, KMAIL3.CNF......)
  129.  
  130.  
  131.       Line #1 can be ONE of the two following examples:
  132.  
  133.         INTERRUPT   ;the best, fastest
  134.         BIOS        ;if interrupt fails to work or if
  135.                     ;running under a multi-tasker
  136.  
  137.       Line #2 is the path\name of a scratch work directory. If the
  138.       sub-directory does not exist, it will be created. The name may
  139.       be anything. I use the name KWORK on my system.
  140.  
  141.       Line #3 is optional. If the pre-zip function (explained later) is
  142.       used, this line points to the holding sub-directory. It may be
  143.       any name, but I recommend something like KHOLD. Multi-node
  144.       systems must share the same KHOLD sub-directory in order for
  145.       pre-zip packets to be located from any node.
  146.  
  147.  
  148.         Sample KMAIL.CNF
  149.  
  150.         INTERRUPT       Line 1
  151.         C:\KWORK        Line 2  <-- Must be unique for each node!
  152.         D:\KHOLD        Line 3  Optional, must NOT be the same as
  153.                                 line 2. Multi-node systems should
  154.                                 share the same sub-directory.
  155.  
  156.   ********************************************************************
  157.   **  Warning   **  Warning  **  Warning  **  Warning  **  Warning  **
  158.   ********************************************************************
  159.   *                                                                  *
  160.   *   ALL FILES ARE ERASED IN THE WORK DIRECTORY DURING PROCESSING.  *
  161.   *   MAKE SURE THE AREA YOU SPECIFY IS A SCRATCH AREA!              *
  162.   *                                                                  *
  163.   *     C:\KWORK    <=== NOTE: All files erased in this dir.         *
  164.   *                                                                  *
  165.   ********************************************************************
  166.   **  Warning   **  Warning  **  Warning  **  Warning  **  Warning  **
  167.   ********************************************************************
  168.  
  169.  
  170.    5. Create the BAT file to run the Kmail door. Kmail requires two
  171.       parameters when it is called. The 1st parameter specifies the
  172.       name of the CONFIG file. The 2nd parameter specifies the
  173.       the drive and path to your PCBoard main directory where the
  174.       PCBOARD.DAT file is located.
  175.  
  176.       Echo off
  177.       SET KMAIL=
  178.       CD\Kmail
  179.       KMAIL KMAIL.CNF C:\PCB
  180.       C:
  181.       CD\PCB
  182.       If exist event.bat event             <<<--- take note
  183.       Board
  184.  
  185.    Notice line 6.  This line will start your timed event if needed.  Any
  186.    door that can logoff a user (during carrier loss or with goodbye) has
  187.    the possibility of starting the event.
  188.  
  189.  
  190.    6. Add an entry in your DOORS.LST files for Kmail. Indicate that
  191.       a USERS.SYS *SHOULD* be created and that a DOOR.SYS should not
  192.       be created when Kmail is executed.
  193.  
  194.    7. Using PCBsm, select "User Info File Maintenance" and create
  195.       a KMAIL Third Party Application entry with the following info.
  196.  
  197.       Version      :    25
  198.       Static Size  :     4
  199.       Dynamic Size :     1
  200.       Keyword      : KMAIL    <---- Watch this one! See note below.
  201.  
  202.       NOTE: The keyword parameter above must match the name of the BAT
  203.             file that is used to open the Kmail door. So, if the name
  204.             of your BAT file is something else, change the keyword
  205.             parameter accordingly.
  206.  
  207.    8. Kmail will use the DOS Environment variable "COMSPEC=" to locate
  208.       COMMAND.COM in order to execute the archive and communications
  209.       programs. The location of the archive and communication programs
  210.       must also be included in your DOS path.
  211.  
  212.    9. Network Qnet Status:
  213.  
  214.       If your system will be acting as a HUB for other systems, then
  215.       you will need to create a QNET.DAT file to control the Qnet status
  216.       of the downline systems. The QNET.DAT file is a plain ordinary
  217.       text file which contains the names of the downline sysops whom
  218.       you wish to grant Qnet status. One name per line starting in
  219.       column 1 and EXACTLY 1 space between the first and last name.
  220.       Mixed case is ok. The QNET.DAT file should be placed in the
  221.       Kmail sub-directory. Qnet status permits a user to upload mail
  222.       on behalf of another person. Without Qnet status, a user is limited
  223.       to uploading only their own personal mail.
  224.  
  225.       (* ----------------------------------------------------------- *)
  226.       (* The sequence of names should NEVER be changed and new names *)
  227.       (* must only be added to the end of the file. If you need to   *)
  228.       (* remove a person from the list, then just XXX their name out *)
  229.       (* leaving the XXX's as a placeholder.                         *)
  230.       (* ----------------------------------------------------------- *)
  231.  
  232.       NOTE: I apologize for the shoddyness of this procedure. I am
  233.             working on a PCBsm type utility to handle this function.
  234.             It is high on the priority list and expect to have something
  235.             near the end of 1Q 1991.
  236.  
  237.       The letter 'Q' is displayed on the conference selection screen
  238.       beside each conference to indicate Qnet status.
  239.  
  240.       If you have one or more conferences that you do not want echoed
  241.       to downline systems, setting the conference echo-flag to NO will
  242.       disable Qnet status for that conference. Messages can still be
  243.       downloaded for offline reading via a RDR, but cannot be merged
  244.       into the system message base.
  245.  
  246.   10. PRE-ZIP'ed mail packets.
  247.  
  248.       This function allows you to scan and zip a mail packet for a
  249.       user so that it is ready for download when the user calls in.
  250.       This is an especially usefull function for LD callers.
  251.  
  252.       You will need to create a sub-directory to serve as a holding
  253.       area for the pre-zipped packets. The location of the holding
  254.       directory is specified in the Kmail.cnf file as shown in step
  255.       (5) above. Multi-node systems may share the same holding area.
  256.  
  257.       A PREZIP.DAT file must be created in the Kmail sub-directory
  258.       which lists each sysop's name and assigns a unique sequence
  259.       number to each name. The sequence numbers are used to match up
  260.       a pre-zip packet with the proper caller and are not associated
  261.       with any other function in Kmail. Pre-zip packets will be
  262.       stored in the KHOLD directory until downloaded by the caller.
  263.       The users "MSG Pointers" are also stored in the KHOLD directory
  264.       and are posted to the users record upon successful downloading
  265.       of the pre-zip packet.
  266.  
  267. Note: The following format must be *strictly* adheared to. The
  268.       name begins in column #1 and must not exceed 25 characters.
  269.       A comma MUST sepatate the name and it's following sequence
  270.       number. All names must have a three digit sequence number
  271.       following the name, leading zeros REQUIRED!  Mixed case is
  272.       allowed in the name. No two users should have the same number!
  273.  
  274.    Sample: PREZIP.DAT
  275.  
  276.       George Washington,026
  277.       John Smith,015
  278.       Bob Jones,009
  279.  
  280.  
  281.       I would suggest a SET Kmail= in your door bat file to insure
  282.       that PREZIP is never active for an online caller.
  283.  
  284.       Prezip processing is activated via a Kmail=PREZIP DOS environment
  285.       variable. The following is suggested in your event.sys file.
  286.  
  287.       Basically, the process is to make a call to PCB145 to build a
  288.       USERS.SYS followed by a call to Kmail to create the packet.
  289.  
  290.       Important! The use of : and ; at the appropriate places in the
  291.                  PCB145 command line is critical!!!
  292.  
  293.          Ex:  PCB145 /USERSYS;JOHN;SMITH;PWRD:12345;TPA:KMAIL
  294.                                                         ^^^^^
  295.       Carefull, this parm must match the bat file name.   |
  296.       ____________________________________________________|
  297.  
  298.       EVENT.SYS
  299.       ...
  300.       ...
  301.       Set Kmail=PREZIP              <===== (note CAPS)
  302.       cd\pcb
  303.       PCB145 /USERSYS;JOHN;SMITH;PWRD:12345;TPA:KMAIL
  304.       cd\Kmail
  305.       Kmail KMAIL.CNF C:\PCB LOCAL
  306.       cd\pcb
  307.       PCB145 /USERSYS;JOE;DOAKS;PWRD:FOOBAR;TPA:KMAIL
  308.       cd\Kmail
  309.       Kmail KMAIL.CNF C:\PCB LOCAL
  310.       If Exist USERS.SYS Del USERS.SYS
  311.       Set Kmail=                 <===== Important!! I suggest you also
  312.       ...                               include this line in your Kmail
  313.       ...                               door BAT file(s).
  314.       event continues.....
  315.  
  316.  
  317.   11. The installation of Kmail is now complete and you are ready to
  318.       begin initial testing as soon as everything is backed up!!!
  319.  
  320.  
  321.   12. Insure that the locations of DSZ and PKZxxx programs are defined
  322.       in your DOS path. Kmail will be unable to locate them if they
  323.       are not in the Dos path!
  324.  
  325.  
  326.     **** NOTE WELL **** NOTE WELL **** NOTE WELL **** NOTE WELL ****
  327.     **** NOTE WELL **** NOTE WELL **** NOTE WELL **** NOTE WELL ****
  328.     **** NOTE WELL **** NOTE WELL **** NOTE WELL **** NOTE WELL ****
  329.  
  330.   Obviously a  mail door  must update  the USERS  file to  store message
  331. pointers.  Please make sure your USERS file is backed up before  running
  332. Kmail.  There has  been one report of  trashed message pointers.   I was
  333. unable to track down the cause of the problem and it has not re-occured.
  334.  
  335.   Do not fall  into the trap  of making an  automatic backup each  night
  336. during  your  event  if  you  are  simply overlaying the previous nights
  337. backup.  If  a problem did  occur and you  did not catch  it for several
  338. days, you wouldn't have a valid backup copy.  I suggest that you keep  a
  339. minimum of seven grandfather copies of  your USERS file and each one  of
  340. them should be unique.
  341.  
  342.  
  343. Conferences
  344. -----------
  345.  
  346.   Kmail obtains all conference  related information from the  CNAMES.@@@
  347. file including  such items  as MSG  base location,  required security to
  348. join, and bulletins path/location.
  349.  
  350.   If  a  user  does  not  have  the  required  security  level to join a
  351. conference,  the  conference  will  be  listed  as <closed> on the Kmail
  352. conference selection menu.
  353.  
  354.   If you need to  delete a conference for  any reason, just insure  that
  355. the conference  name is  blanked out  using PCBsetup  and Kmail will not
  356. attempt to  process it.   It  will show  up as  *Empty* on the selection
  357. menu. Remember to do a global delete of the registered and scan flags!
  358.  
  359.  
  360. Private (R/O) Messages
  361. ----------------------
  362.  
  363.   Kmail will validate the caller  security level and compare it  against
  364. the appropriate values specified in  PCBsetup to determine if access  to
  365. to private messages including comments to sysop are allowed.  Conference
  366. Sysop status  is also  checked.   As with  PCBoard, you  may give global
  367. access to private messages by assigning a high enough security, or on  a
  368. conference by conference basis by assigning conference-sysop status.
  369.  
  370.  
  371. Qnet_Private=No/Yes    (Default=No)
  372. -------------------
  373.  
  374.   If you wish to allow  Network-Sysop's the ability to download  private
  375. mail without having to alter security levels, you can do this be putting
  376. the parameter Qnet_Private=Yes in the Kmail.CFG file.  However, R/O msgs
  377. that do not have  the "Echo" flag set,  will not be sent.   In addition,
  378. the same rule  applies to the  conference "Echo-flag" status.   In other
  379. words, for a R/O message to qualify using the Qnet_Private= option, both
  380. the conference Echo flag  AND the individual msg  Echo flag must be  set
  381. on.  Comments to Sysop are not included with this option.
  382.  
  383.  
  384. Ignore_Echo=No/Yes     (Default=No)
  385. ------------------
  386.  
  387.   In the default mode of operation, if a caller has Network-Status, only
  388. messages with the Echo flag enabled will be included in the mail packet.
  389. The one exception being that any "personal" mail would be included.  The
  390. same holds true for uploading as  well in that a Network-Sysop may  only
  391. upload "personal" mail into a conference that is defined as non-echo.
  392.  
  393.   Specifing Ignore_Echo=YES in the CFG  file will cause Kmail to  ignore
  394. all echo flags and assume everything has "Echo" status.
  395.  
  396.  
  397. Zip_Opt=xxx
  398. -----------
  399.  
  400.   If for some reason you  need/want Kmail to use unique  Zip parameters,
  401. you may specify them using this option.  Omit this entry unless you have
  402. a specific reason for using it.
  403.  
  404.  
  405.  
  406. SCRIPT0 File
  407. ------------
  408.  
  409.   If a SCRIPT0 file is present  in the KMAIL directory, it will  be sent
  410. along in the mail packet.  The SCRIPT0 file is displayed by the  various
  411. readers  when  the  user  exits  the  reader.    If you use one of those
  412. programs that generate  a different SCRIPT0  every day, you  may want to
  413. consider copying  it over  to the  Kmail directory  during system  event
  414. processing.
  415.  
  416. Getting Started
  417. ---------------
  418.  
  419.   Finally it's time to run Kmail.  Just login  to the BBS in the  normal
  420. way and open  Kmail door.   As a first  time user, you  will be asked to
  421. answer some  configuration questions  as will  each user  when they  try
  422. Kmail the first time.  A  special feature in Kmail will detect  when the
  423. "sysop" is in local mode and  will issue a prompt asking where  to place
  424. the resulting QWK mail  packet.  You should  respond with the drive  and
  425. path, but WITHOUT the trailing back-slash after the name.
  426.  
  427.        c:\temp     \      All of these are valid ways to specify the
  428.        d:\ez        >--   location of where to place the QWK  packet
  429.        a:          /      when running in local mode.
  430.  
  431.   Later on when you are ready to upload any replies created with one  of
  432. the offline readers, Kmail will ask  where to obtain the REP file.   Use
  433. the same format as above to specify the location.
  434.  
  435.  
  436. Errors
  437. ------
  438.  
  439.   Any errors detected by kmail  including those from 3rd party  programs
  440. such as PKZip  and DSZ are  logged into a  file called $door.err  in the
  441. Kmail sub-directory.  In addition,  many of the errors are  also written
  442. to the  caller log  file.   Error information  is also  displayed to the
  443. callers.
  444.  
  445.  
  446. Notes and Misc Info
  447. -------------------
  448.  
  449.   Kmail  sends  a  KMAIL.PTR  file  in  each  mail packet.  The PTR file
  450. contains the last-read message pointer for each conference that the user
  451. has selected.  In the event of a problem, a user may upload the PTR file
  452. to restore the message pointers.   Just extract the KMAIL.PTR  file from
  453. the QWK packet and zip it up in a BBSID.REP file and upload it to  Kmail
  454. using the 'P' menu option.
  455.  
  456.  
  457.   The user may select/un-select  conferences and reset message  pointers
  458. by using the  appropriate options in  EZ-RDR.  Review  the documentation
  459. associated  with  EZ-RDR  for  additional  information.   When resetting
  460. message pointers, Kmail will accept an absolute message # or a  negative
  461. number such  as -25  which means  set the  message pointer  equal to  25
  462. messages from the end of the message base.
  463.  
  464.   Not yet documented on the menu screen is the ability to stack commands
  465. for the  download process.   The  command 'D  Y' will  download the mail
  466. packet and return you to the menu screen, while 'D G' will download  and
  467. log you off.  A 10 second timer is provided to allow you to change  your
  468. mind.  By using  stacked commands, the user  can avoid the question  "Do
  469. you wish to receive this packet?"
  470.  
  471.   Recent changes to PCBoard allow for passing command line parms to door
  472. programs. Kmail now takes advantage of this feature. Assuming  Kmail was
  473. installed as door #3, the following commands would be valid.
  474.          Open 3 d       (open the door & start download scan)
  475.          Open 3 d y     (open the door, scan mail, yes to download)
  476.          Open 3 d g     (open the door, scan mail, download & goodbye)
  477.         Kmail d y       (open the door, scan mail, yes to download)
  478.  
  479.  
  480. In The Works
  481. ------------
  482.  
  483. Utility to handle Qnet status and view/change user options.
  484.  
  485. Online and downloadable help information is planned.
  486.  
  487. A filter to allow a user to not receive messages from selected users.
  488.  
  489. Acknowledgements
  490. ----------------
  491.  
  492. Special thanks to Bill Walsh, whose system I crashed many times during
  493. early beta testing, and to Jeff Freeman whose eagle eye caught many
  494. potential problems, and to Ken Flower for testing >256 conferences.
  495. And thanks to the many others who played a part in the beta testing
  496. development of Kmail.
  497.  
  498.  
  499. Registration
  500. ------------
  501.  
  502.   Please see the file KMAIL.REG for registration information.
  503.  
  504.   After receipt of your registration, you  will need to call my BBS  and
  505. obtain a customized KEY file, which will enable any and all features not
  506. available  in  the  evaluation  copy  of  Kmail.    Currently,  the only
  507. limitation is the number of messages allowed per mail packet.
  508.  
  509.   After obtaining your customized KMAIL.KEY file, just place it in  your
  510. KMAIL sub-directory to activate all features.
  511.  
  512.  
  513.                                  Ken Krueger
  514.                                  Twin Peak's BBS
  515.                            303-651-0225 - Hayes Ultra 9600 v.32
  516.